3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Quaternions

QuickDraw 3D provides routines that you can use to operate on quaternions.

Q3Quaternion_Set

You can use the Q3Quaternion_Set function to set the components of a quaternion.



 
TQ3Quaternion *Q3Quaternion_Set (

                     TQ3Quaternion *quaternion, 

                     float w, 

                     float x, 

                     float y, 

                     float z);

quaternion: A quaternion.
w: The desired w component of a quaternion.
x: The desired x component of a quaternion.
y: The desired y component of a quaternion.
z: The desired z component of a quaternion.

DESCRIPTION

The Q3Quaternion_Set function returns, as its function result and in the quaternion parameter, the quaternion whose components are specified by the w , x , y , and z parameters.

Q3Quaternion_SetIdentity

You can use the Q3Quaternion_SetIdentity function to set a quaternion to the identity quaternion.



 
TQ3Quaternion *Q3Quaternion_SetIdentity (

                     TQ3Quaternion *quaternion);

quaternion: On exit, the identity quaternion.

DESCRIPTION

The Q3Quaternion_SetIdentity function returns, as its function result and in the quaternion parameter, the identity quaternion.

Q3Quaternion_Copy

You can use the Q3Quaternion_Copy function to get a copy of a quaternion.



 
TQ3Quaternion *Q3Quaternion_Copy (

                     const TQ3Quaternion *quaternion, 

                     TQ3Quaternion *result);

quaternion: A quaternion.
result: On exit, a copy of quaternion .

DESCRIPTION

The Q3Quaternion_Copy function returns, as its function result and in the result parameter, a copy of the quaternion quaternion .

Q3Quaternion_IsIdentity

You can use the Q3Quaternion_IsIdentity function to determine whether a quaternion is the identity quaternion.



 
TQ3Boolean Q3Quaternion_IsIdentity (

                     const TQ3Quaternion *quaternion);

quaternion: A quaternion.

DESCRIPTION

The Q3Quaternion_IsIdentity function returns kQ3True if the quaternion parameter is the identity quaternion; Q3Quaternion_IsIdentity returns kQ3False otherwise.

Q3Quaternion_Invert

You can use the Q3Quaternion_Invert function to invert a quaternion.



 
TQ3Quaternion *Q3Quaternion_Invert (

                     const TQ3Quaternion *quaternion, 

                     TQ3Quaternion *result);

quaternion: A quaternion.
result: On exit, the inverse of quaternion .

DESCRIPTION

The Q3Quaternion_Invert function returns, as its function result and in the result parameter, the inverse of the quaternion specified by the quaternion parameter.

Q3Quaternion_Normalize

You can use the Q3Quaternion_Normalize function to normalize a quaternion.



 
TQ3Quaternion *Q3Quaternion_Normalize (

                     const TQ3Quaternion *quaternion, 

                     TQ3Quaternion *result);

quaternion: A quaternion.
result: On exit, the normalized form of quaternion .

DESCRIPTION

The Q3Quaternion_Normalize function returns, as its function result and in the result parameter, the normalized form of the quaternion quaternion . Note that on entry the result parameter can be the same as the quaternion parameter.

Q3Quaternion_Dot

You can use the Q3Quaternion_Dot function to determine the dot product of two quaternions.



 
float Q3Quaternion_Dot (

                     const TQ3Quaternion *q1, 

                     const TQ3Quaternion *q2);

q1: A quaternion.
q2: A quaternion.

DESCRIPTION

The Q3Quaternion_Dot function returns, as its function result, a floating-point value that is the dot product of the two quaternions q1 and q2 .

Q3Quaternion_Multiply

You can use the Q3Quaternion_Multiply function to multiply two quaternions.



 
TQ3Quaternion *Q3Quaternion_Multiply (

                     const TQ3Quaternion *q1, 

                     const TQ3Quaternion *q2, 

                     TQ3Quaternion *result);

q1: A quaternion.
q2: A quaternion.
result: On exit, the product of q1 and q2 .

DESCRIPTION

The Q3Quaternion_Multiply function returns, as its function result and in the result parameter, the product of the two quaternions q1 and q2 .

If you want to rotate an object by the quaternion qFirst and then rotate the resulting object by the quaternion qSecond , you can accomplish both rotations at once by applying the quaternion qResult that is obtained as follows:



 
Q3Quaternion_Multiply(qSecond, qFirst, qResult);

Note the order of the quaternion multiplicands.

Q3Quaternion_SetRotateAboutAxis

You can use the Q3Quaternion_SetRotateAboutAxis function to configure a rotate-about-axis quaternion.



 
TQ3Quaternion *Q3Quaternion_SetRotateAboutAxis (

                     TQ3Quaternion *quaternion, 

                     const TQ3Vector3D *axis, 

                     float angle);

quaternion: A quaternion.
axis: The desired axis of rotation.
angle: The desired angle of rotation, in radians.

DESCRIPTION

The Q3Quaternion_SetRotateAboutAxis function returns, as its function result and in the quaternion parameter, a rotate-about-axis quaternion that rotates an object by the angle angle around the axis specified by the axis parameter.

Q3Quaternion_SetRotate_X

You can use the Q3Quaternion_SetRotate_X function to configure a quaternion that rotates objects around the x axis.



 
TQ3Quaternion *Q3Quaternion_SetRotate_X (

                     TQ3Quaternion *quaternion, 

                     float angle);

quaternion: A quaternion.
angle: The desired angle of rotation around the x coordinate axis, in radians.

DESCRIPTION

The Q3Quaternion_SetRotate_X function returns, as its function result and in the quaternion parameter, a quaternion that rotates an object by the angle angle around the x axis.

Q3Quaternion_SetRotate_Y

You can use the Q3Quaternion_SetRotate_Y function to configure a quaternion that rotates objects around the y axis.



 
TQ3Quaternion *Q3Quaternion_SetRotate_Y (

                     TQ3Quaternion *quaternion, 

                     float angle);

quaternion: A quaternion.
angle: The desired angle of rotation around the y coordinate axis, in radians.

DESCRIPTION

The Q3Quaternion_SetRotate_Y function returns, as its function result and in the quaternion parameter, a quaternion that rotates an object by the angle angle around the y axis.

Q3Quaternion_SetRotate_Z

You can use the Q3Quaternion_SetRotate_Z function to configure a quaternion that rotates objects around the z axis.



 
TQ3Quaternion *Q3Quaternion_SetRotate_Z (

                     TQ3Quaternion *quaternion, 

                     float angle);

quaternion: A quaternion.
angle: The desired angle of rotation around the z coordinate axis, in radians.

DESCRIPTION

The Q3Quaternion_SetRotate_Z function returns, as its function result and in the quaternion parameter, a quaternion that rotates an object by the angle angle around the z axis.

Q3Quaternion_SetRotate_XYZ

You can use the Q3Quaternion_SetRotate_XYZ function to configure a quaternion having a specified rotation around the x, y, and z axes.



 
TQ3Quaternion *Q3Quaternion_SetRotate_XYZ (

                     TQ3Quaternion *quaternion, 

                     float xAngle, 

                     float yAngle, 

                     float zAngle);

quaternion: A quaternion.
xAngle: The desired angle of rotation around the x axis, in radians.
yAngle: The desired angle of rotation around the y axis, in radians.
zAngle: The desired angle of rotation around the z axis, in radians.

DESCRIPTION

The Q3Quaternion_SetRotate_XYZ function returns, as its function result and in the quaternion parameter, a quaternion that rotates an object by the specified angles around the x , y , and z axes.

Q3Quaternion_SetMatrix

You can use the Q3Quaternion_SetMatrix function to configure a quaternion from a matrix.



 
TQ3Quaternion *Q3Quaternion_SetMatrix (

                     TQ3Quaternion *quaternion, 

                     const TQ3Matrix4x4 *matrix);

quaternion: A quaternion.
matrix: A 4-by-by matrix.

DESCRIPTION

The Q3Quaternion_SetMatrix function returns, as its function result and in the quaternion parameter, a quaternion that has the same transformational properties as the matrix specified by the matrix parameter.

Q3Quaternion_SetRotateVectorToVector

You can use the Q3Quaternion_SetRotateVectorToVector function to configure a quaternion that rotates objects around the origin in such a way that a transformed vector matches a given vector.



 
TQ3Quaternion *Q3Quaternion_SetRotateVectorToVector (

                     TQ3Quaternion *quaternion, 

                     const TQ3Vector3D *v1, 

                     const TQ3Vector3D *v2);

quaternion: A quaternion.
v1: A three-dimensional vector.
v2: A three-dimensional vector.

DESCRIPTION

The Q3Quaternion_SetRotateVectorToVector function returns, as its function result and in the quaternion parameter, a quaternion that rotates objects around the origin in such a way that the transformed vector v1 matches the vector v2 . Both v1 and v2 should be normalized.

Q3Quaternion_MatchReflection

You can use the Q3Quaternion_MatchReflection function to match the orientation of a quaternion.



 
TQ3Quaternion *Q3Quaternion_MatchReflection (

                     const TQ3Quaternion *q1, 

                     const TQ3Quaternion *q2, 

                     TQ3Quaternion *result);

q1: A quaternion.
q2: A quaternion.
result: On exit, a quaternion that is either q1 or the negative of q1 , and that matches the orientation of q2 .

DESCRIPTION

The Q3Quaternion_MatchReflection function returns, as its function result and in the result parameter, a quaternion that is either identical to the quaternion specified by the q1 parameter or is the negative of q1 , depending on whether q1 or its negative matches the orientation of the quaternion specified by the q2 parameter.

Q3Quaternion_InterpolateFast

You can use the Q3Quaternion_InterpolateFast function to interpolate quickly between two quaternions.



 
TQ3Quaternion *Q3Quaternion_InterpolateFast (

                     const TQ3Quaternion *q1, 

                     const TQ3Quaternion *q2, 

                     float t, 

                     TQ3Quaternion *result);

q1: A quaternion.
q2: A quaternion.
t: An interpolation factor. This parameter should contain a value between 0.0 and 1.0.
result: On exit, a quaternion that is a fast interpolation between the two specified quaternions.

DESCRIPTION

The Q3Quaternion_InterpolateFast function returns, as its function result and in the result parameter, a quaternion that interpolates between the two quaternions specified by the q1 and q2 parameters, according to the factor specified by the t parameter. If the value of t is 0.0, Q3Quaternion_InterpolateFast returns a quaternion identical to q1 . If the value of t is 1.0, Q3Quaternion_InterpolateFast returns a quaternion identical to q2 . If t is any other value in the range [0.0, 1.0], Q3Quaternion_InterpolateFast returns a quaternion that is interpolated between the two quaternions.

The interpolation returned by Q3Quaternion_InterpolateFast is not as smooth or constant as that returned by Q3Quaternion_InterpolateLinear , but Q3Quaternion_InterpolateFast is usually faster than Q3Quaternion_InterpolateLinear .

Q3Quaternion_InterpolateLinear

You can use the Q3Quaternion_InterpolateLinear function to interpolate linearly between two quaternions.



 
TQ3Quaternion *Q3Quaternion_InterpolateLinear (

                     const TQ3Quaternion *q1, 

                     const TQ3Quaternion *q2, 

                     float t, 

                     TQ3Quaternion *result) ;

q1: A quaternion.
q2: A quaternion.
t: An interpolation factor. This parameter should contain a value between 0.0 and 1.0.
result: On exit, a quaternion that is a smooth and constant interpolation between the two specified quaternions.

DESCRIPTION

The Q3Quaternion_InterpolateLinear function returns, as its function result and in the result parameter, a quaternion that interpolates smoothly between the two quaternions specified by the q1 and q2 parameters, according to the factor specified by the t parameter. If the value of t is 0.0, Q3Quaternion_InterpolateLinear returns a quaternion identical to q1 . If the value of t is 1.0, Q3Quaternion_InterpolateLinear returns a quaternion identical to q2 . If t is any other value in the range [0.0, 1.0], Q3Quaternion_InterpolateLinear returns a quaternion that is interpolated between the two quaternions in a smooth and constant manner.

Q3Vector3D_TransformQuaternion

You can use the Q3Vector3D_TransformQuaternion function to transform a vector by a quaternion.



 
TQ3Vector3D *Q3Vector3D_TransformQuaternion (

                     const TQ3Vector3D *vector, 

                     const TQ3Quaternion *quaternion, 

                     TQ3Vector3D *result);

vector: A three-dimensional vector.
quaternion: A quaternion.
result: On exit, a three-dimensional vector that is the result of transforming the specified vector by the specified quaternion.

DESCRIPTION

The Q3Vector3D_TransformQuaternion function returns, as its function result and in the result parameter, a three-dimensional vector that is the result of transforming the vector specified by the vector parameter using the quaternion specified by the quaternion parameter.

Q3Point3D_TransformQuaternion

You can use the Q3Point3D_TransformQuaternion function to transform a point by a quaternion.



 
TQ3Point3D *Q3Point3D_TransformQuaternion (

                     const TQ3Point3D *point, 

                     const TQ3Quaternion *quaternion, 

                     TQ3Point3D *result);

point: A three-dimensional point.
quaternion: A quaternion.
result: On exit, a three-dimensional point that is the result of transforming the specified point by the specified quaternion.

DESCRIPTION

The Q3Point3D_TransformQuaternion function returns, as its function result and in the result parameter, a three-dimensional point that is the result of transforming the point specified by the point parameter using the quaternion specified by the quaternion parameter.